Skip to main content

API Pagination

Overview​

IQM's API supports filtering and sorting in many of its endpoints. By either passing query or request parameters, results can be filtered for certain keywords or entity IDs, or, sorted to a specified order.

Filtering and sorting parameters​

The Parameters Table below lists the most common filtering and sorting fields used in the IQM API. Their usage will vary based on the endpoint. They will often have a default value if a value is not specified. The default value will be listed as part of an endpoint's documentation if it exists.

Parameters
ids
integer		Filter results by entity ID (varies by endpoint)
searchField / keywords
string		Search results by keyword
limit / noOfEntries
integer		Maximum number of entries returned per page
pageNo
integer		Page number for the returned data
sortBy / order
string		Sorts by ascending (+) or descending (-), the supported values will be listed
offset
integer		Specifies the number of rows of results to skip before data is retrieved. Functions counter to pageNo, and only one can be used at a time with limit/noOfEntries. First priority will be given to offset if used at the same time as pageNo

Examples​

Filter by ID​

Many endpoint will support filtering by some kind of entity ID. The exact parameter will vary based on the entity. For example, the Get List of Campaigns endpoint supports filtering by conversionId. When a Conversion ID is passed as a query, the endpoint returns all Campaign IDs that are associated with that Conversion at the top of the results.

Query Example
https://app.iqm.com/api/v2/cmp/campaigns/data?conversionId=18
Response 200
{
  "statusCode": 200,
  "responseObject": {
    "totalRecords": 1498,
    "data": [
      {
        "id": 176881,
        "name": "Campaign to test duplicate  copy",
        "creativeTypeId": 14,
        "campaignType": "CPV",
        "status": "pending",
        "advertiserId": 100419,
        "created": 1620024156,
        "modifiedDate": 1621571575,
        "conversionId": 18
      },
      {
        "id": 176880,
        "name": "Campaign to test duplicate update",
        "creativeTypeId": 14,
        "campaignType": "CPV",
        "status": "pending",
        "advertiserId": 100419,
        "created": 1620024050,
        "modifiedDate": 1621571575,
        "conversionId": 18
      },
      ...
    ],
    "filteredRecords": 1039
  }
}

Filter by Keywords​

In this example the results are filtered with a search keyword. The Get State Segment endpoint uses the POST method, and therefore its pagination parameters will be passed with a JSON formatted request instead of a query.

Request Sample
{
    "searchField": "California"
}
Response 200
{
    "success": true,
    "data": {
        "data": [
            {
                "id": 30212611,
                "name": "Baja California Sur",
                "parentId": 30100154,
                "geojsonUrl": "https://d3jme5si7t6llb.cloudfront.net/statedata/.geojson"
            },
            {
                "id": 30212610,
                "name": "Baja California",
                "parentId": 30100154,
                "geojsonUrl": "https://d3jme5si7t6llb.cloudfront.net/statedata/.geojson"
            },
            {
                "id": 30200005,
                "name": "California",
                "abbreviation": "CA",
                "parentId": 30100001,
                "geojsonUrl": "https://d3jme5si7t6llb.cloudfront.net/statedata/CA.geojson"
            }
        ],
        "totalRecords": 4964,
        "filteredRecords": 3
    }
}

Filter the Number of Entries​

The maximum number of entries returned can be specified with the noOfEntries (or sometimes limit) query parameter. Below two entries are retrieved from the Get List of Inventories endpoint.

Query Example
https://app.iqm.com/api/v3/inv/inventories/list?noOfEntries=2
Response 200
{
    "success": true,
    "data": {
        "inventoryDataList": [
            {
                "id": 13097078,
                "name": "com.twitter.android",
                "publisher": "adx_pub-3661441281163245",
                "appId": "com.twitter.android",
                "inventoryType": "Android App",
                "impressions": 2698270955,
                "reach": 56406049,
                "videoPercentage": 0.0,
                "displayPercentage": 0.0
            },
            {
                "id": 34520,
                "name": "METROPCS-METROZONE",
                "publisher": "adx_pub-2964924015572549",
                "appId": "com.metropcs.metrozone",
                "inventoryType": "Android App",
                "impressions": 2319549000,
                "reach": 115747223,
                "videoPercentage": 22.769272,
                "displayPercentage": 48.073381
            }
        ]
    }
}

Filter by Page Number​

When the possible number of results exceeds the limit that can be returned, there will be a pageNo parameter to specify which page of results will be returned. Keeping with the example in the previous section, if a page number of "2" is appended in addition to the two entries, the next two records will be retrieved.

Query Example
https://app.iqm.com/api/v3/inv/inventories/list?noOfEntries=2&pageNo=2
Response 200
{
    "success": true,
    "data": {
        "inventoryDataList": [
            {
                "id": 13106651,
                "name": "X",
                "publisher": "adx_pub-3661441281163245",
                "appId": "333903271",
                "inventoryType": "IOS App",
                "impressions": 1413114383,
                "reach": 57020310,
                "videoPercentage": 0.020887,
                "displayPercentage": 0.0
            },
            {
                "id": 4777647,
                "name": "Samsung TV Plus Free",
                "publisher": "Samsung",
                "appId": "g15147002586",
                "inventoryType": "Other App",
                "impressions": 583064989,
                "reach": 24606677,
                "videoPercentage": 100.0,
                "displayPercentage": 0.0
            }
        ]
    }
}

Sort the Results​

Lists of results can often be sorted by a specified parameter. Using the sortBy query in the Get List of Campaigns endpoint, the returned list of Campaigns can be sorted by ascending or descending by appending a + or - symbol to the desired parameter. In this example, the results are sorted by -created: the descending order of creation date.

Query Example
https://app.iqm.com/api/v2/cmp/campaigns/data?sortBy=-created
Response 200
{
  "statusCode": 200,
  "responseObject": {
    "totalRecords": 1498,
    "data": [
      {
        "id": 176881,
        "name": "Campaign to test duplicate  copy",
        "creativeTypeId": 14,
        "campaignType": "CPV",
        "status": "pending",
        "advertiserId": 100419,
        "created": 1620024156,
        "modifiedDate": 1621571575,
        "conversionId": 18
      },
      {
        "id": 176880,
        "name": "Campaign to test duplicate update",
        "creativeTypeId": 14,
        "campaignType": "CPV",
        "status": "pending",
        "advertiserId": 100419,
        "created": 1620024050,
        "modifiedDate": 1621571575,
        "conversionId": 18
      },
      {
        "id": 176879,
        "name": "to test campaign duplication",
        "creativeTypeId": 11,
        "campaignType": "CPM",
        "status": "pending",
        "advertiserId": 100419,
        "created": 1620023582,
        "modifiedDate": 1620024188
      },
      {
        "id": 176148,
        "name": "campaign to test Inventory group and all device type",
        "creativeTypeId": 11,
        "campaignType": "CPM",
        "status": "pending",
        "advertiserId": 100419,
        "created": 1618990887,
        "modifiedDate": 1618992828
      },
      {
        "id": 173357,
        "name": "test cb",
        "creativeTypeId": 11,
        "campaignType": "CPM",
        "status": "running",
        "advertiserId": 100001,
        "created": 1617170692,
        "modifiedDate": 1619433624
      },
      {
        "id": 173353,
        "name": "test cb",
        "creativeTypeId": 11,
        "campaignType": "CPM",
        "status": "running",
        "advertiserId": 100001,
        "created": 1617163055,
        "modifiedDate": 1619433624
      },
      {
        "id": 173318,
        "name": "test cb1",
        "creativeTypeId": 11,
        "campaignType": "CPM",
        "status": "running",
        "advertiserId": 100001,
        "created": 1617130075,
        "modifiedDate": 1619433624
      },
      {
        "id": 173317,
        "name": "test cb",
        "creativeTypeId": 11,
        "campaignType": "CPM",
        "status": "running",
        "advertiserId": 100001,
        "created": 1617126490,
        "modifiedDate": 1619433624
      },
      {
        "id": 173316,
        "name": "test old cb",
        "creativeTypeId": 11,
        "campaignType": "CPM",
        "status": "running",
        "advertiserId": 100001,
        "created": 1617125771,
        "modifiedDate": 1619433624
      },
      {
        "id": 169459,
        "name": "test daily",
        "creativeTypeId": 11,
        "campaignType": "CPM",
        "status": "pending",
        "advertiserId": 100419,
        "created": 1611734667,
        "modifiedDate": 1618992828
      }
    ],
    "filteredRecords": 1039
  }
}